<?php

/**
 * This code was generated by
 * \ / _    _  _|   _  _
 * | (_)\/(_)(_|\/| |(/_  v1.0.0
 * /       /
 */

namespace Twilio\Rest\IpMessaging\V1\Service;

use Twilio\ListResource;
use Twilio\Serialize;
use Twilio\Values;
use Twilio\Version;

class RoleList extends ListResource {
	/**
	 * Construct the RoleList
	 *
	 * @param Version $version Version that contains the resource
	 * @param string $serviceSid The unique id of the Service this role belongs to.
	 *
	 * @return \Twilio\Rest\IpMessaging\V1\Service\RoleList
	 */
	public function __construct( Version $version, $serviceSid ) {
		parent::__construct( $version );

		// Path Solution
		$this->solution = array( 'serviceSid' => $serviceSid, );

		$this->uri = '/Services/' . rawurlencode( $serviceSid ) . '/Roles';
	}

	/**
	 * Create a new RoleInstance
	 *
	 * @param string $friendlyName The human-readable name of this role.
	 * @param string $type What kind of role this is.
	 * @param string $permission A permission this role should have.
	 *
	 * @return RoleInstance Newly created RoleInstance
	 * @throws TwilioException When an HTTP error occurs.
	 */
	public function create( $friendlyName, $type, $permission ) {
		$data = Values::of( array(
			'FriendlyName' => $friendlyName,
			'Type'         => $type,
			'Permission'   => Serialize::map( $permission, function ( $e ) {
				return $e;
			} ),
		) );

		$payload = $this->version->create(
			'POST',
			$this->uri,
			array(),
			$data
		);

		return new RoleInstance( $this->version, $payload, $this->solution['serviceSid'] );
	}

	/**
	 * Reads RoleInstance records from the API as a list.
	 * Unlike stream(), this operation is eager and will load `limit` records into
	 * memory before returning.
	 *
	 * @param int $limit Upper limit for the number of records to return. read()
	 *                   guarantees to never return more than limit.  Default is no
	 *                   limit
	 * @param mixed $pageSize Number of records to fetch per request, when not set
	 *                        will use the default value of 50 records.  If no
	 *                        page_size is defined but a limit is defined, read()
	 *                        will attempt to read the limit with the most
	 *                        efficient page size, i.e. min(limit, 1000)
	 *
	 * @return RoleInstance[] Array of results
	 */
	public function read( $limit = null, $pageSize = null ) {
		return iterator_to_array( $this->stream( $limit, $pageSize ), false );
	}

	/**
	 * Streams RoleInstance records from the API as a generator stream.
	 * This operation lazily loads records as efficiently as possible until the
	 * limit
	 * is reached.
	 * The results are returned as a generator, so this operation is memory
	 * efficient.
	 *
	 * @param int $limit Upper limit for the number of records to return. stream()
	 *                   guarantees to never return more than limit.  Default is no
	 *                   limit
	 * @param mixed $pageSize Number of records to fetch per request, when not set
	 *                        will use the default value of 50 records.  If no
	 *                        page_size is defined but a limit is defined, stream()
	 *                        will attempt to read the limit with the most
	 *                        efficient page size, i.e. min(limit, 1000)
	 *
	 * @return \Twilio\Stream stream of results
	 */
	public function stream( $limit = null, $pageSize = null ) {
		$limits = $this->version->readLimits( $limit, $pageSize );

		$page = $this->page( $limits['pageSize'] );

		return $this->version->stream( $page, $limits['limit'], $limits['pageLimit'] );
	}

	/**
	 * Retrieve a single page of RoleInstance records from the API.
	 * Request is executed immediately
	 *
	 * @param mixed $pageSize Number of records to return, defaults to 50
	 * @param string $pageToken PageToken provided by the API
	 * @param mixed $pageNumber Page Number, this value is simply for client state
	 *
	 * @return \Twilio\Page Page of RoleInstance
	 */
	public function page( $pageSize = Values::NONE, $pageToken = Values::NONE, $pageNumber = Values::NONE ) {
		$params = Values::of( array(
			'PageToken' => $pageToken,
			'Page'      => $pageNumber,
			'PageSize'  => $pageSize,
		) );

		$response = $this->version->page(
			'GET',
			$this->uri,
			$params
		);

		return new RolePage( $this->version, $response, $this->solution );
	}

	/**
	 * Retrieve a specific page of RoleInstance records from the API.
	 * Request is executed immediately
	 *
	 * @param string $targetUrl API-generated URL for the requested results page
	 *
	 * @return \Twilio\Page Page of RoleInstance
	 */
	public function getPage( $targetUrl ) {
		$response = $this->version->getDomain()->getClient()->request(
			'GET',
			$targetUrl
		);

		return new RolePage( $this->version, $response, $this->solution );
	}

	/**
	 * Constructs a RoleContext
	 *
	 * @param string $sid The sid
	 *
	 * @return \Twilio\Rest\IpMessaging\V1\Service\RoleContext
	 */
	public function getContext( $sid ) {
		return new RoleContext( $this->version, $this->solution['serviceSid'], $sid );
	}

	/**
	 * Provide a friendly representation
	 *
	 * @return string Machine friendly representation
	 */
	public function __toString() {
		return '[Twilio.IpMessaging.V1.RoleList]';
	}
}